package com.smart.community.property.service;

import java.math.BigDecimal;
import java.time.LocalDate;
import java.util.List;
import java.util.Map;

import com.baomidou.mybatisplus.extension.service.IService;
import com.smart.community.commons.result.PageResult;
import com.smart.community.property.dto.BatchPropertyFeeDTO;
import com.smart.community.property.dto.PropertyFeeDTO;
import com.smart.community.property.dto.PropertyFeeEditDTO;
import com.smart.community.property.dto.RepairOrderDTO;
import com.smart.community.property.entity.PropertyFee;
import com.smart.community.property.vo.PropertyFeeStatisticsVO;
import com.smart.community.property.vo.PropertyFeeVO;
import com.smart.community.property.vo.RepairOrderStatisticsVO;
import com.smart.community.property.vo.RepairOrderVO;
import com.smart.community.property.vo.RepairmanVO;

/**
 * 物业管理Service接口 - 重构版本
 * 专注于物业费管理和维修工单管理，遵循单一职责原则
 * @author Wu.Liang
 * @since 2025-06-26
 * @version 2.0.0
 */
public interface IPropertyService extends IService<PropertyFee> {
    
    // ========================= 物业费管理 =========================
    
    /**
     * 分页查询物业费账单
     * @param propertyFeeDTO 查询条件
     * @return 分页结果
     */
    PageResult<PropertyFeeVO> pagePropertyBills(PropertyFeeDTO propertyFeeDTO);
    
    /**
     * 查询当前用户的物业费账单
     * @param current 当前页
     * @param size 每页大小
     * @param paymentStatus 缴费状态
     * @param feeType 费用类型
     * @param billingPeriod 计费周期
     * @return 分页结果
     */
    PageResult<PropertyFeeVO> getMyPropertyFees(Integer current, Integer size, Integer paymentStatus, Integer feeType, String billingPeriod);
    
    /**
     * 获取物业费详情
     * @param billId 账单ID
     * @return 账单详情
     */
    PropertyFeeVO getPropertyFeeDetail(Long billId);
    
    /**
     * 获取物业费详情（App端专用）
     * 验证当前用户是否为该房户的业主
     * @param billId 账单ID
     * @param userId 用户ID
     * @return 账单详情
     */
    PropertyFeeVO getPropertyFeeDetailForMobile(Long billId, Long userId);
    
    /**
     * 验证用户对费用的权限（App端专用）
     * 判断当前用户是否为该房户的业主
     * @param feeId 费用ID
     * @param userId 用户ID
     */
    void validateUserPermissionForFee(Long feeId, Long userId);
    
    /**
     * 更新物业费信息
     * @param billId 账单ID
     * @param propertyFeeDTO 更新数据
     * @return 是否更新成功
     * @ 统一异常
     */
    boolean updatePropertyFee(Long billId, PropertyFeeDTO propertyFeeDTO) ;
    
    /**
     * 编辑物业费信息（仅允许编辑指定字段）
     * @param billId 账单ID
     * @param editDTO 编辑数据
     * @return 是否编辑成功
     * @ 统一异常
     */
    boolean editPropertyFee(Long billId, PropertyFeeEditDTO editDTO) ;
    
    /**
     * 缴费
     * @param billId 账单ID
     * @param paymentAmount 支付金额
     * @param paymentMethod 支付方式
     * @return 是否缴费成功
     * @ 统一异常
     */
    boolean payBill(Long billId, BigDecimal paymentAmount, String paymentMethod) ;
    
    /**
     * 生成物业费账单
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @return 生成的账单数量
     * @ 统一异常
     */
    int generatePropertyBills(Long communityId, LocalDate billingMonth) ;
    
    /**
     * 生成物业费账单
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param dueDate 到期日期
     * @return 生成的账单数量
     * @ 统一异常
     */
    int generatePropertyBills(Long communityId, LocalDate billingMonth, LocalDate dueDate) ;
    
    /**
     * 生成费用账单
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param feeType 费用类型：1-物业费，2-水费，3-电费，4-燃气费，5-卫生费
     * @return 生成的账单数量
     * @ 统一异常
     */
    int generatePropertyBills(Long communityId, LocalDate billingMonth, Integer feeType) ;
    
    /**
     * 生成费用账单
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param feeType 费用类型：1-物业费，2-水费，3-电费，4-燃气费，5-卫生费
     * @param dueDate 到期日期
     * @return 生成的账单数量
     * @ 统一异常
     */
    int generatePropertyBills(Long communityId, LocalDate billingMonth, Integer feeType, LocalDate dueDate) ;
    
    /**
     * 生成费用账单（带人均费用）
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param feeType 费用类型：1-物业费，2-水费，3-电费，4-燃气费，5-卫生费
     * @param perPersonFee 人均费用
     * @return 生成的账单数量
     * @ 统一异常
     */
    int generatePropertyBills(Long communityId, LocalDate billingMonth, Integer feeType, BigDecimal perPersonFee) ;
    
    /**
     * 生成费用账单（带人均费用）
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param feeType 费用类型：1-物业费，2-水费，3-电费，4-燃气费，5-卫生费
     * @param perPersonFee 人均费用
     * @param dueDate 到期日期
     * @return 生成的账单数量
     */
    int generatePropertyBills(Long communityId, LocalDate billingMonth, Integer feeType, BigDecimal perPersonFee, LocalDate dueDate);
    
    /**
     * 生成费用账单（带人均费用，使用String类型的费用类型）
     * @param communityId 社区ID
     * @param billingMonth 计费月份
     * @param feeType 费用类型：1-物业费，2-水费，3-电费，4-燃气费，5-卫生费
     * @param perPersonFee 人均费用
     * @param dueDate 到期日期
     * @return 生成的账单数量
     */
    int generatePropertyBills(Long communityId, LocalDate billingMonth, String feeType, BigDecimal perPersonFee, LocalDate dueDate);
    
    /**
     * 批量生成物业费账单
     * @param batchDTO 批量生成参数
     * @return 生成结果统计
     * @ 统一异常
     */
    Map<String, Integer> batchGeneratePropertyBills(BatchPropertyFeeDTO batchDTO) ;
    
    /**
     * 发送催缴提醒
     * @param billId 账单ID
     * @param remindType 提醒方式：sms-短信，email-邮件，app-APP推送
     * @return 是否发送成功
     * @ 统一异常
     */
    boolean sendPaymentReminder(Long billId, String remindType) ;
    
    /**
     * 批量发送催缴提醒
     * @param communityId 社区ID
     * @param remindType 提醒方式
     * @return 发送结果统计
     * @ 统一异常
     */
    Map<String, Integer> batchSendPaymentReminder(Long communityId, String remindType) ;
    
    /**
     * 根据用户ID查询未缴费账单
     * @param userId 用户ID
     * @return 未缴费账单列表
     * @ 统一异常
     */
    List<PropertyFeeVO> getUnpaidBillsByUserId(Long userId) ;
    
    /**
     * 导出物业费账单
     * @param propertyFeeDTO 查询条件
     * @return 导出文件路径
     * @ 统一异常
     */
    String exportPropertyFeeBills(PropertyFeeDTO propertyFeeDTO) ;
    
    // ========================= 统计分析 =========================
    
    /**
     * 获取物业费收缴统计
     * @param communityId 社区ID
     * @param year 年份
     * @return 收缴统计
     * @ 统一异常
     */
    PropertyFeeStatisticsVO getPropertyFeeStatistics(Long communityId, Integer year) ;
    
    /**
     * 获取物业费月度统计
     * @param communityId 社区ID
     * @param year 年份
     * @return 月度统计列表
     * @ 统一异常
     */
    List<PropertyFeeStatisticsVO> getMonthlyPropertyFeeStatistics(Long communityId, Integer year) ;
    
    // ========================= 维修工单管理 =========================
    
    /**
     * 分页查询维修工单
     * @param current 当前页
     * @param size 每页大小
     * @param communityId 社区ID
     * @param status 状态
     * @return 分页结果
     * @ 统一异常
     */
    PageResult<RepairOrderVO> pageRepairOrders(Integer current, Integer size, Long communityId, Integer status) ;
    
    /**
     * 获取维修工单详情
     * @param orderId 工单ID
     * @return 工单详情
     * @ 统一异常
     */
    RepairOrderVO getRepairOrderDetail(Long orderId) ;
    
    /**
     * 提交维修工单
     * @param repairOrderDTO 维修工单信息
     * @return 工单ID
     * @ 统一异常
     */
    Long submitRepairOrder(RepairOrderDTO repairOrderDTO) ;
    
    /**
     * 更新维修工单状态
     * @param orderId 工单ID
     * @param status 工单状态
     * @param remark 备注
     * @return 是否更新成功
     * @ 统一异常
     */
    boolean updateRepairOrderStatus(Long orderId, Integer status, String remark) ;
    
    /**
     * 分配维修工单
     * @param orderId 工单ID
     * @param repairmanId 维修人员ID
     * @param remark 分配备注
     * @return 是否分配成功
     * @ 统一异常
     */
    boolean assignRepairOrder(Long orderId, Long repairmanId, String remark) ;
    
    /**
     * 批量分配维修工单
     * @param orderIds 工单ID列表
     * @param repairmanId 维修人员ID
     * @return 分配结果统计
     * @ 统一异常
     */
    Map<String, Integer> batchAssignRepairOrders(List<Long> orderIds, Long repairmanId) ;
    
    /**
     * 完成维修工单
     * @param orderId 工单ID
     * @param result 维修结果
     * @param satisfaction 满意度评分（保留参数以兼容旧接口）
     * @param remark 完成备注
     * @return 是否完成成功
     * @ 统一异常
     */
    boolean completeRepairOrder(Long orderId, String result, Integer satisfaction, String remark) ;
    
    /**
     * 获取维修工单统计信息
     * @param communityId 社区ID
     * @param startDate 开始日期
     * @param endDate 结束日期
     * @return 统计信息
     * @ 统一异常
     */
    RepairOrderStatisticsVO getRepairOrderStatistics(Long communityId, LocalDate startDate, LocalDate endDate) ;
    
    // ========================= 维修人员管理 =========================
    
    /**
     * 获取维修人员列表
     * @param communityId 社区ID
     * @param status 状态：1-可用，0-不可用
     * @return 维修人员列表
     * @ 统一异常
     */
    List<RepairmanVO> getRepairmanList(Long communityId, Integer status) ;
    
    // ========================= 缓存管理 =========================
    
    /**
     * 清除物业费相关缓存
     * @param communityId 社区ID
     * @ 统一异常
     */
    void clearPropertyFeeCache(Long communityId) ;
    
    /**
     * 清除用户物业费缓存
     * @param userId 用户ID
     * @ 统一异常
     */
    void clearUserPropertyFeeCache(Long userId) ;

    /**
     * 生成物业费账单（支持计费月份时间段，根据计费方式自动计算）
     * @param communityId 社区ID
     * @param billingMonthRange 计费月份时间段
     * @param dueDate 到期日期
     * @param remark 备注
     * @return 生成的账单数量
     * @ 统一异常
     */
    int generatePropertyFeeByRange(Long communityId, List<String> billingMonthRange, 
                                  String dueDate, String remark) ;
} 